QuickTime 3 Reference

Parameter Descriptions

Each effect component supplies a parameter description data structure that describes in detail the set of parameters that the effect has.

This section describes the parameter description format in detail. You need this information if you are writing an effect component and need to provide a parameter description as part of an 'atms' resource (see "Supplying Parameter Description Information" for more details).

You may also need this information if you are writing an application that needs to present its own user interface for setting effect parameters. In this case, you will need to parse parameter descriptions to generate appropriate controls to set parameter values.

Any software that uses an effect can request its parameter description. Typically, the parameter description is then passed to QTCreateStandardParameterDialog or especially, ImageCodecCreateStandardParameterDialog . These functions use the parameter description to display a user interface that allows users to choose the values of the parameters.

Your are free to use the information in an effect's parameter description in other ways. For example, your application can use the default value atoms to construct an effect description.

Parameter descriptions are stored as a QTAtomContainer , and you retrieve an effect's description by calling ImageCodecGetParameterList . This function takes a component instance and returns the parameter description for that component.

The code shown in Listing 31 opens the component specified in the variable subType . The code sets up the component description, then finds and opens the requested component. It then calls the ImageCodecGetParameterList function to fill out the parameter description for this effect.

Listing 31 Opening the image decompressor component



 
{

    // Set up a component description

    cd.componentType    = 'imdc';       // Effects are image decompressor

                                        // components

    cd.componentSubType = subType;      // This is the name of the effect

                                        //(e.g. 'smpt')

    cd.componentManufacturer    = 0;

    cd.componentFlags           = 0;

    cd.componentFlagsMask       = 0;



    // Find the required component. If it can't be found, generate an

    // error

    if ((theComponent = FindNextComponent(theComponent, &cd))==0)

    {

        err = paramErr;

        goto bail;

    }



    // Open the component

    gCompInstance = OpenComponent(theComponent);



    // Get the parameter description for the effect

    ImageCodecGetParameterList(gCompInstance, &parameterDescription);

}

Your application can parse the returned parameter description using the standard QuickTime APIs that query QTAtomContainer data structures. This can be useful if your application deals with effect components whose parameter list is not known ahead of time. In particular, if your application maintains its own user interface for users to customize effects, it will need to read and understand parameter descriptions.

This section describes the general format of the data returned in a parameter description.

The Parameter Description Format